/* Foley C# Utilities
 * Copyright (C)2002 Rodney S. Foley
 *  
 * This program is free software; you can 
 * redistribute it and/or modify it under the 
 * terms of the GNU General Public License as 
 * published by the Free Software Foundation; 
 * either version 2 of the License, or (at your 
 * option) any later version.
 * 
 * This program is distributed in the hope that 
 * it will be useful, but WITHOUT ANY WARRANTY; 
 * without even the implied warranty of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR 
 * PURPOSE. See the GNU General Public License 
 * for more details.
 * 
 * You should have received a copy of the GNU 
 * General Public License along with this 
 * program; if not, write to: 
 * 
 *		Free Software Foundation, Inc., 
 *		59 Temple Place, Suite 330, 
 *		Boston, MA 02111-1307 USA
 * 
 *					- or -
 *  
 * http://opensource.org/licenses/gpl-license.php
 */

using System;
using System.Collections;

namespace Foley.Utilities.Collections
{
	/// <summary>
	/// Represents a collection of objects that contains no duplicate elements.
	/// </summary>
	/// <remarks>
	/// <para>
	/// <see cref="ISet"/> is a descendant of the <see cref="ICollection2"/> 
	/// <c>interface</c> and is the base <c>interface</c> for all sets.
	/// </para>
	/// Example: If you have <c>element1</c> and <c>element12</c> then 
	/// <c>element1.Equals(element12)</c> cannot be <c><c>true</c></c> inside 
	/// the set, and if <c>null</c> is allowed then no more than one <c>null</c>
	/// element in a set. 
	/// <para>
	/// It is therefore recommend that the user of the set understand how the 
	/// objects contained in it are handled by their <c>Equals</c> method. 
	/// </para>
	/// A set, unless otherwise stated, does not gaurentee it's elements to be 
	/// contiguous.
	/// </remarks>
	public interface ISet : ICollection2
	{
		/// <summary>
		/// When implemented by a class, adds an <see cref="object"/> to the set.
		/// </summary>
		/// <param name="value">
		/// The <see cref="object"/> to add to the set.
		/// </param>
		/// <returns>
		/// <c>true</c> if the <see cref="object"/> was successfully added; 
		/// otherwise, <c>false</c>.
		/// </returns>
		/// <exception cref="NotSupportedException">
		/// <para>The set is read-only.</para>
		/// -or-
		/// <para>The set has a fixed size.</para>
		/// </exception>
		bool Add(object value);

		/// <summary>
		/// When implemented by a class, adds all the elements in the specified
		/// collection that are not already contained in the set.
		/// </summary>
		/// <param name="collection">
		/// The <see cref="ICollection"/> whose elements are to be added to
		/// the set.
		/// </param>
		/// <returns>
		/// <c>true</c> if the set is modified; otherwise <c>false</c>.
		/// </returns>
		/// <exception cref="NotSupportedException">
		/// <para>The set is read-only.</para>
		/// -or-
		/// <para>The set has a fixed size.</para>
		/// </exception>
		bool Add(ICollection collection);

		/// <summary>
		/// When implemented by a class, determines whether the set contains
		/// the specific <see cref="object"/>.
		/// </summary>
		/// <param name="value">
		/// The <see cref="object"/> to locate in the set.
		/// </param>
		/// <returns>
		/// <c>true</c> if the <see cref="object"/> is found in the set; 
		/// otherwise, <c>false</c>.
		/// </returns>
		bool Contains(object value);

		/// <summary>
		/// When implemented by a class determines whether the set contains all 
		/// of the elements of the specified <see cref="ICollection"/>.
		/// </summary>
		/// <param name="collection">
		/// The <see cref="ICollection"/> used to determine if all its elements
		/// are contained within the set.
		/// </param>
		/// <returns>
		/// <c>true</c> if all the elements are found in the set; otherwise, 
		/// <c>false</c>.
		/// </returns>
		bool Contains(ICollection collection);

		/// <summary>
		/// When implemented by a class, removes the specific <see cref="object"/> 
		/// from the set.
		/// </summary>
		/// <param name="value">
		/// The <see cref="object"/> to remove from the set. 
		/// </param>
		/// <returns>
		/// <c>true</c> if the set is modified; otherwise <c>false</c>.
		/// </returns>
		/// <exception cref="NotSupportedException">
		/// <para>The set is read-only.</para>
		/// -or-
		/// <para>The set has a fixed size.</para>
		/// </exception>
		bool Remove(object value);

		/// <summary>
		/// When implemented by a class, removes each element of the specified 
		/// <see cref="ICollection"/> from the set.
		/// </summary>
		/// <param name="collection">
		/// The <see cref="ICollection"/> used to determine what elements to 
		/// remove from the set.
		/// </param>
		/// <returns>
		/// <c>true</c> if the set is modified; otherwise <c>false</c>.
		/// </returns>
		/// <exception cref="NotSupportedException">
		/// <para>The set is read-only.</para>
		/// -or-
		/// <para>The set has a fixed size.</para>
		/// </exception>
		bool Remove(ICollection collection);

		/// <summary>
		/// When implemented by a class, retains each element of the specified
		/// <see cref="ICollection"/> in the set.
		/// </summary>
		/// <param name="collection">
		/// The <see cref="ICollection"/> used to determine what elements to be 
		/// retained in the set.
		/// </param>
		/// <returns>
		/// <c>true</c> if the set is modified; otherwise <c>false</c>.
		/// </returns>
		/// <exception cref="NotSupportedException">
		/// <para>The set is read-only.</para>
		/// -or-
		/// <para>The set has a fixed size.</para>
		/// </exception>
		bool Retain(ICollection collection);
	}
}
